Publish v0.1 envelope JSON Schema + tx-protocol 0.1.0-alpha.2 release#2
Merged
Conversation
Adds zod-to-json-schema-based generator script that publishes the PreparedTransaction Envelope v0.1 JSON Schema to the canonical URL `https://txkit.dev/schemas/v0.1/envelope.json` (served from the landing app's public directory). Output drives the normative `$schema` URL referenced by every prepared envelope per the ERC submission Specification section 1.2. Regenerable via `pnpm --filter @txkit/tx-protocol gen:schema`. Initial generation reflects the pre-alpha.2 state of zod sources; follow-up commit drops the legacy `version` field per locked ERC design decision.
Bumps `@txkit/tx-protocol` to 0.1.0-alpha.2 with 5 breaking changes aligning the reference implementation with the ERC submission draft: 1. Drop envelope-level `version: SpecVersion` field. The `$schema` URL is the version contract; embedding a redundant version inside the envelope was retired during Phase 3 ERC body draft. 2. Drop post-quantum scheme enum entries (`ml-dsa-44`, `ml-dsa-65`, `ml-dsa-87`, `slh-dsa-sha2-128s`) from `SignatureScheme`. The open string fallback covers future schemes without unverifiable claims; specific PQ values return in a follow-up once NIST FIPS 204/205 final status is independently verified. 3. Rename `requiresAccountType: 'smart-account-7702'` to `'delegated-eoa'`. The new value is account-shape-typed rather than protocol-typed so future delegation transports do not require new enum values; removes the explicit EIP-7702 protocol-level claim from the normative enum. 4. Close `RiskWarning.severity` to `'low' | 'medium' | 'high' | 'critical'`. Aligns with ERC section 7 closed enumeration; replaces the previous `INFO | WARN | CRITICAL` set. 5. Close `ScannerVerdict.verdict` to `'ALLOW' | 'WARN' | 'BLOCK'`. Matches `RiskAssessment.action` vocabulary in ERC section 7. Also adds: - `examples/multicall-batch.ts` demonstrating `evm-batch` kind with `atomicRequired: true` capability and multi-call `tokenMovements` covering approve + transfer in a single envelope. - Canonical spec sync at `spec/v0.1/prepared-transaction.md`. - Updated test fixtures in `validate.spec.ts` and downstream consumer adjustment in `packages/ows-adapter`. Regenerates `app/landing/public/schemas/v0.1/envelope.json` from the post-bump zod sources; the envelope no longer carries a redundant `version` field. The remaining `version` properties in the schema are the `Eip712Domain.version` field per EIP-712 typed-data, not envelope metadata. Verification: - `pnpm --filter @txkit/tx-protocol typecheck` clean - `pnpm --filter @txkit/tx-protocol test` 20/20 pass
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
PreparedTransaction Envelope v0.1JSON Schema at the canonical URLhttps://txkit.dev/schemas/v0.1/envelope.json(served fromapp/landing/public/)zod-to-json-schema-based generator (pnpm --filter @txkit/tx-protocol gen:schema) so future v0.N schema revisions stay in lockstep with the zod source of truth@txkit/tx-protocol@0.1.0-alpha.2with 5 breaking changes aligning the reference implementation with the ERC submission draft body (dropversionfield, drop unverifiable PQ scheme enum entries, renamesmart-account-7702todelegated-eoa, close severity + verdict enums)examples/multicall-batch.tscovering theevm-batchkind withatomicRequired+ multi-calltokenMovementsWhy now
The ERC submission draft (
PreparedTransaction Envelope, scheduled for ethereum/ERCs PR in Phase 6) carries a normative reference to the canonical schema URL in Specification section 1.2. Until this PR ships, that URL returns 404. Phase 5 pre-Magicians soft outreach (starting today, 2026-05-12) shares the draft body with named reviewers via gist; reviewers who follow the$schemalink from the worked Permit2 example or anywhere else would land on a broken URL. Publishing the schema artifact closes that gap and lets reviewers validate envelope payloads against an authoritative document.The alpha.2 release was documented in
STATUS.mdas a Phase 6 prerequisite and is bundled here because the regenerated schema must reflect the post-bump zod source (noversionfield, renamed account type, closed enums).Changes
Schema generator
packages/tx-protocol/scripts/generate-schema.ts- callszodToJsonSchema(preparedEnvelopeSchema), augments with$schema(JSON Schema 2020-12) +$id(canonical txkit.dev URL) + title + description, writes to landing apppackages/tx-protocol/package.json- addsgen:schemanpm script +zod-to-json-schema+tsxdevDepsPublished schema artifact
app/landing/public/schemas/v0.1/envelope.json- 29KB JSON Schema covering all three normative kinds (evm-tx,evm-batch,signature) plus every field defined in ERC sections 1 through 10Reference implementation alignment (
@txkit/tx-protocol0.1.0-alpha.0 -> 0.1.0-alpha.2)version: SpecVersionfromBaseEnvelope. The$schemaURL is the version contract.ml-dsa-*,slh-dsa-*) fromSignatureScheme. Open string fallback covers future schemes; specific PQ values return after NIST FIPS 204/205 final status independently verified.'smart-account-7702'->'delegated-eoa'inRequiredAccountType. Account-shape-typed rather than protocol-typed; removes explicit EIP-7702 protocol-level claim from normative enum.RiskWarning.severityto'low' | 'medium' | 'high' | 'critical'. Aligns with ERC section 7 closed enumeration.ScannerVerdict.verdictto'ALLOW' | 'WARN' | 'BLOCK'. MatchesRiskAssessment.actionvocabulary.Files touched
app/landing/public/schemas/v0.1/envelope.json(new)packages/tx-protocol/scripts/generate-schema.ts(new)packages/tx-protocol/examples/multicall-batch.ts(new)packages/tx-protocol/package.json(version bump + devDeps + script)packages/tx-protocol/CHANGELOG.md(alpha.2 entry)packages/tx-protocol/spec/v0.1/prepared-transaction.md(canonical spec sync)packages/tx-protocol/src/schema.ts(drop version field, drop PQ enums, rename account type, close enums)packages/tx-protocol/src/types.ts(matching type changes)packages/tx-protocol/src/helpers.ts(drop SPEC_VERSION import + usage in create helpers)packages/tx-protocol/src/index.ts(drop SPEC_VERSION + SpecVersion exports)packages/tx-protocol/src/__tests__/validate.spec.ts(assertion updates)packages/ows-adapter/src/__tests__/ows.spec.ts(downstream severity update)pnpm-lock.yaml(devDeps install)Test plan
pnpm --filter @txkit/tx-protocol typecheckcleanpnpm --filter @txkit/tx-protocol test20/20 passpnpm --filter @txkit/tx-protocol gen:schemawrites deterministic outputcurl https://txkit.dev/schemas/v0.1/envelope.jsonreturns 200 with valid JSON Schema after Vercel auto-deploy landsexamples/multicall-batch.tsenvelope output validates against the published schemaNotes
The remaining
versionproperties in the generated schema (Eip712Domain.version) are the EIP-712 typed-data domain version per the EIP-712 specification, not the dropped envelope-level field.The schema generator runs entirely against the zod source of truth, so any future divergence between the zod runtime validators and the published JSON Schema would be a code review issue rather than a drift risk.